package com.gitee.helioz.openai.api.dto.images;

import com.gitee.helioz.openai.common.util.http.HttpFilePart;
import com.google.gson.annotations.SerializedName;
import lombok.Data;

/**
 * 〈图片编辑请求〉
 *
 * @author <a href="https://gitee.com/helioz">Morning Starr</a>
 */
@Data
public class ImageEditRequest {
    /**
     * 待编辑的图片的 URL。图片必须满足以下条件：
     * <pre>
     * 必须是有效的 PNG 文件格式。
     * 文件大小必须小于 4MB。
     * 图片必须是正方形，宽度和高度必须相等。</pre>
     * 如果没有提供蒙版（mask），图片必须具有透明度，这将在图片编辑过程中被用作蒙版。蒙版用于定义根据指定的图片编辑指令进行修改或编辑的区域。
     * <pre>必填</pre>
     */
    private HttpFilePart image;
    /**
     * 蒙版图片（mask）是另外一张图片，其中完全透明的区域（例如 alpha 通道值为零的区域）指示了需要编辑的位置。
     * <pre>
     * 蒙版图片必须符合以下要求：
     * 必须是有效的 PNG 文件格式。
     * 文件大小必须小于 4MB。
     * 蒙版图片必须与待编辑的图片具有相同的尺寸，即宽度和高度必须相等。</pre>
     * <pre>选填</pre>
     */
    private HttpFilePart mask;
    /**
     * 生成图像的文本描述。您可以提供一个文本描述，描述您期望生成的图像的外观、内容或其他特性。这个文本描述将作为生成图像的输入，帮助模型理解您的需求。
     * 请注意，文本描述的最大长度限制为1000个字符。超过这个限制的文本描述将被截断或被 API 拒绝。
     * 因此，在提供文本描述时，请确保在1000个字符内，并清晰明了地描述您的需求，以获得最佳的生成图像结果。
     * <pre>必填</pre>
     */
    private String prompt;
    /**
     * 默认值：1，指定生成的图像数量。您可以设置一个介于1和10之间的整数值，以确定您希望生成的图像数量。
     * <p>例如，如果您将此参数设置为5，API 将生成5张图像作为响应返回。
     * 请注意，生成的图像数量越多，请求的处理时间可能会增加。因此，您可以根据您的应用需求和性能要求来设置合适的图像生成数量。</p>
     * <pre>选填</pre>
     */
    private Integer n;
    /**
     * 默认值：1024x1024，指定生成的图像的尺寸。可以选择以下三种尺寸：
     * <pre>
     * 256x256: 生成的图像尺寸为 256x256 像素。
     * 512x512: 生成的图像尺寸为 512x512 像素。
     * 1024x1024: 生成的图像尺寸为 1024x1024 像素。
     * </pre>
     * <pre>选填</pre>
     * @see com.gitee.helioz.openai.api.dto.images.SizeEnum
     */
    private String size;
    /**
     * 默认值：url，指定生成的图像返回的格式。可以选择以下两种格式：
     * <pre>
     * url: 图像以 URL 的形式返回，可以通过该 URL 进行访问和下载。
     * b64_json: 图像以 base64 编码的 JSON 格式返回，可以在 API 响应中获取图像的二进制数据，并进行解码以获取图像。
     * </pre>
     * <pre>选填</pre>
     * @see com.gitee.helioz.openai.api.dto.images.ResponseFormatEnum
     */
    @SerializedName("response_format")
    private String responseFormat;
    /**
     * 用于表示您的终端用户的唯一标识符，以帮助 OpenAI 监测和检测滥用行为。
     * 该参数通常用于防止滥用 API，并对 API 使用进行限制。您可以根据您的应用需求为终端用户生成一个唯一的标识符，
     * 例如用户的会话ID、用户ID或其他标识符，并将其作为请求参数传递给 OpenAI API。
     * 这样，OpenAI 可以根据该标识符来识别和跟踪特定用户的 API 请求，并进行必要的监测和检测。
     * <pre>选填</pre>
     */
    private String user;
}
